Developer CD Series 1994 November: Tool Chest/Dev.CD Nov 94.toast/Sample Code/MoreFiles 1.2.1/MoreFiles.p

Text File | 1994-07-22 | 23.9 KB | 641 lines | [TEXT/PJMM]

UNIT MoreFiles;

{    Apple Macintosh Developer Technical Support                                }
{                                                                            }
{    The long lost high-level and FSSpec File Manager functions.                }
{    by Jim Luther, Apple Developer Technical Support                        }
{                                                                            }
{    File:        MoreFiles.p                                                    }
{                                                                            }
{    Copyright © 1992-1994 Apple Computer, Inc.                                }
{    All rights reserved.                                                    }
{                                                                            }
{    You may incorporate this sample code into your applications without        }
{    restriction, though the sample code has been provided "AS IS" and the    }
{    responsibility for its operation is 100% yours.  However, what you are    }
{    not permitted to do is to redistribute the source as "DSC Sample Code"    }
{    after having made changes. If you're going to re-distribute the source,    }
{    we require that you make it clear in the source that the code was        }
{    descended from Apple Sample Code, but that you've made changes.            }


INTERFACE

{***************************************************************************}


    FUNCTION HGetVolParms (volName: StringPtr;
                                    vRefNum: Integer;
                                    VAR volParmsInfo: GetVolParmsInfoBuffer;
                                    VAR infoSize: LongInt): OSErr;
{    Use HGetVolParms to determine the characteristics of a volume.            }
{    A result of paramErr usually just means the volume doesn't                }
{    support PBHGetVolParms and the feature you were going to check            }
{    for isn't available.                                                    }
{                                                                            }
{    volName            input:    A pointer to the name of a mounted volume        }
{                            or nil.                                            }
{    vRefNum            input:    Volume specification.                            }
{    volParmsInfo    input:    Pointer to GetVolParmsInfoBuffer where the        }
{                            volume attributes information is returned.        }
{                    output:    Atributes information.                            }
{    infoSize        input:    Size of buffer pointed to by volParmsInfo.        }
{                    output: Size of data actually returned.                    }


{***************************************************************************}


    FUNCTION HCreateMinimum (vRefNum: Integer;
                                    dirID: LongInt;
                                    fileName: Str255): OSErr;
{    Use HCreateMinimum to create a new file without attempting to set the    }
{    creator and file type of the new file.  This function is needed to        }
{    create a file in an AppleShare "drop box" where the user can make        }
{    changes, but cannot see folder or files.                                }
{                                                                            }
{    vRefNum        input:    Volume specification.                                }
{    dirID        input:    Directory ID.                                        }
{    fileName    input:    The name of the new file.                            }


{***************************************************************************}


    FUNCTION FSpCreateMinimum (spec: FSSpec): OSErr;
{    Use FSpCreateMinimum to create a new file without attempting to set        }
{    the creator and file type of the new file.  This function is needed to    }
{    create a file in an AppleShare "dropbox" where the user can make        }
{    changes, but cannot see folder or files.                                }
{                                                                            }
{    spec        input:    An FSSpec record specifying the file to create.        }


{***************************************************************************}


    FUNCTION ExchangeFiles (vRefNum: Integer;
                                    srcDirID: LongInt;
                                    srcName: Str255;
                                    dstDirID: LongInt;
                                    dstName: Str255): OSErr;
{    Use ExchangeFiles to exchange the data stored in two files on the        }
{    same volume.                                                            }
{                                                                            }
{    vRefNum        input:    Volume specification.                                }
{    srcDirID    input:    Source directory ID.                                }
{    srcName        input:    Source file name.                                    }
{    dstDirID    input:    Destination directory ID.                            }
{    dstName        input:    Destination file name.                                }


{***************************************************************************}


    FUNCTION ResolveFileIDRef (volName: StringPtr;
                                    vRefNum: Integer;
                                    fileID: LongInt;
                                    VAR parID: LongInt;
                                    fileName: StringPtr): OSErr;
{    Use ResolveFileIDRef to retrieve the filename and parent directory ID    }
{    of the file with the specified file ID.                                    }
{                                                                            }
{    volName    input:    A pointer to the name of a mounted volume                }
{                    or nil.                                                    }
{    fileID    input:    The file ID.                                            }
{    vRefNum    input:    Volume specification.                                    }
{    parID    output:    The parent directory ID of the file.                    }
{    name    input:    Points to a buffer (minimum Str63) where the filename    }
{                    is to be returned or must be nil.                        }
{            output:    The filename.                                            }


{***************************************************************************}


    FUNCTION CreateFileIDRef (vRefNum: Integer;
                                    parID: LongInt;
                                    fileName: Str255;
                                    VAR fileID: LongInt): OSErr;
{    Use CreateFileIDRef to establish a file ID for a file.                    }
{                                                                            }
{    vRefNum        input:    Volume specification.                                }
{    parID        input:    Directory ID.                                        }
{    fileName    input:    The name of the file.                                }
{    fileID        output:    The file ID.                                        }


{***************************************************************************}


    FUNCTION FSpCreateFileIDRef (spec: FSSpec;
                                    VAR fileID: LongInt): OSErr;
{    Use FSpCreateFileIDRef to establish a file ID for a file.                }
{                                                                            }
{    spec        input:    An FSSpec record specifying the file.                }
{    fileID        output:    The file ID.                                        }


{***************************************************************************}


    FUNCTION DeleteFileIDRef (volName: StringPtr;
                                    vRefNum: Integer;
                                    fileID: LongInt): OSErr;
{    Use DeleteFileIDRef to delete a file ID reference.                        }
{                                                                            }
{    volName    input:    A pointer to the name of a mounted volume                }
{                    or nil.                                                    }
{    vRefNum    input:    Volume specification.                                    }
{    fileID    input:    The file ID.                                            }


{***************************************************************************}


    FUNCTION FlushFile (refNum: Integer): OSErr;
{    Use FlushFile to write the contents of a file's access path buffer.        }
{                                                                            }
{    refNum    input:    The file reference number of an open file.                }


{***************************************************************************}


    FUNCTION LockRange (refNum: Integer;
                                    rangeLength: LongInt;
                                    rangeStart: LongInt): OSErr;
{    Use LockRange to lock a portion of a file.                                }
{                                                                            }
{    refNum        input:    The file reference number of an open file.            }
{    rangeLength    input:    The number of bytes in the range.                    }
{    rangeStart    input:    The starting byte in the range to lock.                }


{***************************************************************************}


    FUNCTION UnlockRange (refNum: Integer;
                                    rangeLength: LongInt;
                                    rangeStart: LongInt): OSErr;
{    Use UnlockRange to unlock a previously locked range.                    }
{                                                                            }
{    refNum        input:    The file reference number of an open file.            }
{    rangeLength    input:    The number of bytes in the range.                    }
{    rangeStart    input:    The starting byte in the range to unlock.            }


{***************************************************************************}


    FUNCTION GetForeignPrivs (vRefNum: Integer;
                                    dirID: LongInt;
                                    name: StringPtr;
                                    foreignPrivBuffer: Ptr;
                                    VAR foreignPrivSize: LongInt;
                                    VAR foreignPrivInfo1: LongInt;
                                    VAR foreignPrivInfo2: LongInt;
                                    VAR foreignPrivInfo3: LongInt;
                                    VAR foreignPrivInfo4: LongInt): OSErr;
{    Use GetForeignPrivs to determine the native access-control                }
{    information for a file or directory stored on a volume managed by        }
{    a foreign file system.                                                    }
{                                                                            }
{    vRefNum                input:    Volume specification.                        }
{    dirID                input:    Directory ID.                                }
{    name                input:    Pointer to object name, or nil when dirID    }
{                                specifies a directory that's the object.    }
{    foreignPrivBuffer    input:    Pointer to buffer where the privilege        }
{                                information is returned.                    }
{                        output:    Privilege information.                        }
{    foreignPrivSize        input:    Size of buffer pointed to by                }
{                                foreignPrivBuffer.                            }
{                        output: Amount of buffer actually used.                }
{    foreignPrivInfo1    output:    Information specific to privilege model.    }
{    foreignPrivInfo2    output:    Information specific to privilege model.    }
{    foreignPrivInfo3    output:    Information specific to privilege model.    }
{    foreignPrivInfo4    output:    Information specific to privilege model.    }


{***************************************************************************}


    FUNCTION FSpGetForeignPrivs (spec: FSSpec;
                                    foreignPrivBuffer: Ptr;
                                    VAR foreignPrivSize: LongInt;
                                    VAR foreignPrivInfo1: LongInt;
                                    VAR foreignPrivInfo2: LongInt;
                                    VAR foreignPrivInfo3: LongInt;
                                    VAR foreignPrivInfo4: LongInt): OSErr;
{    Use FSpGetForeignPrivs to determine the native access-control            }
{    information for a file or directory stored on a volume managed by        }
{    a foreign file system.                                                    }
{                                                                            }
{    spec                input:    An FSSpec record specifying the object.        }
{    foreignPrivBuffer    input:    Pointer to buffer where the privilege        }
{                                information is returned.                    }
{                        output:    Privilege information.                        }
{    foreignPrivSize        input:    Size of buffer pointed to by                }
{                                foreignPrivBuffer.                            }
{                        output: Amount of buffer actually used.                }
{    foreignPrivInfo1    output:    Information specific to privilege model.    }
{    foreignPrivInfo2    output:    Information specific to privilege model.    }
{    foreignPrivInfo3    output:    Information specific to privilege model.    }
{    foreignPrivInfo4    output:    Information specific to privilege model.    }



{***************************************************************************}


    FUNCTION SetForeignPrivs (vRefNum: Integer;
                                    dirID: LongInt;
                                    name: StringPtr;
                                    foreignPrivBuffer: Ptr;
                                    VAR foreignPrivSize: LongInt;
                                    foreignPrivInfo1: LongInt;
                                    foreignPrivInfo2: LongInt;
                                    foreignPrivInfo3: LongInt;
                                    foreignPrivInfo4: LongInt): OSErr;
{    Use SetForeignPrivs to change the native access-control information        }
{    for a file or directory stored on a volume managed by a foreign            }
{    file system.                                                            }
{                                                                            }
{    vRefNum                input:    Volume specification.                        }
{    dirID                input:    Directory ID.                                }
{    name                input:    Pointer to object name, or nil when dirID    }
{                                specifies a directory that's the object.    }
{    foreignPrivBuffer    input:    Pointer to privilege information buffer.    }
{    foreignPrivSize        input:    Size of buffer pointed to by                }
{                                foreignPrivBuffer.                            }
{                        output: Amount of buffer actually used.                }
{    foreignPrivInfo1    input:    Information specific to privilege model.    }
{    foreignPrivInfo2    input:    Information specific to privilege model.    }
{    foreignPrivInfo3    input:    Information specific to privilege model.    }
{    foreignPrivInfo4    input:    Information specific to privilege model.    }


{***************************************************************************}


    FUNCTION FSpSetForeignPrivs (spec: FSSpec;
                                    foreignPrivBuffer: Ptr;
                                    VAR foreignPrivSize: LongInt;
                                    foreignPrivInfo1: LongInt;
                                    foreignPrivInfo2: LongInt;
                                    foreignPrivInfo3: LongInt;
                                    foreignPrivInfo4: LongInt): OSErr;
{    Use FSpSetForeignPrivs to change the native access-control information    }
{    for a file or directory stored on a volume managed by a foreign            }
{    file system.                                                            }
{                                                                            }
{    spec                input:    An FSSpec record specifying the object.        }
{    foreignPrivBuffer    input:    Pointer to privilege information buffer.    }
{    foreignPrivSize        input:    Size of buffer pointed to by                }
{                                foreignPrivBuffer.                            }
{                        output: Amount of buffer actually used.                }
{    foreignPrivInfo1    input:    Information specific to privilege model.    }
{    foreignPrivInfo2    input:    Information specific to privilege model.    }
{    foreignPrivInfo3    input:    Information specific to privilege model.    }
{    foreignPrivInfo4    input:    Information specific to privilege model.    }


{***************************************************************************}


    FUNCTION HGetLogInInfo (volName: StringPtr;
                                    vRefNum: Integer;
                                    VAR loginMethod: Integer;
                                    userName: StringPtr): OSErr;
{    Use HGetLogInInfo to determine the login method and user name used to    }
{    log on to a particular shared volume.                                    }
{                                                                            }
{    volName        input:    A pointer to the name of a mounted volume            }
{                        or nil.                                                }
{    vRefNum        input:    The volume reference number.                        }
{    loginMethod    output:    The login method used (kNoUserAuthentication,        }
{                        kPassword, kEncryptPassword, or                        }
{                        kTwoWayEncryptPassword).                            }
{    userName    input:    Points to a buffer (minimum Str31) where the user    }
{                        name is to be returned or must be nil.                }
{                output:    The user name.                                        }


{***************************************************************************}


    FUNCTION HGetDirAccess (vRefNum: Integer;
                                    dirID: LongInt;
                                    name: StringPtr;
                                    VAR ownerID: LongInt;
                                    VAR groupID: LongInt;
                                    VAR accessRights: LongInt): OSErr;
{    Use HGetDirAccess to get the directory access control information for    }
{    a directory on a shared volume.                                            }
{                                                                            }
{    vRefNum            input:    Volume specification.                            }
{    dirID            input:    Directory ID.                                    }
{    name            input:    Pointer to directory name, or nil if dirID        }
{                            specifies the directory.                        }
{    ownerID            output:    The directory's owner ID.                        }
{    groupID            output:    The directory's group ID or                        }
{                            0 if no group affiliation.                        }
{    accessRights    output:    The directory's access rights.                    }


{***************************************************************************}


    FUNCTION FSpGetDirAccess (spec: FSSpec;
                                    VAR ownerID: LongInt;
                                    VAR groupID: LongInt;
                                    VAR accessRights: LongInt): OSErr;
{    Use FSpGetDirAccess to get the directory access control information        }
{    for a directory on a shared volume.                                        }
{                                                                            }
{    spec            input:    An FSSpec record specifying the directory.        }
{    ownerID            output:    The directory's owner ID.                        }
{    groupID            output:    The directory's group ID or                        }
{                            0 if no group affiliation.                        }
{    accessRights    output:    The directory's access rights.                    }


{***************************************************************************}


    FUNCTION HSetDirAccess (vRefNum: Integer;
                                    dirID: LongInt;
                                    name: StringPtr;
                                    ownerID: LongInt;
                                    groupID: LongInt;
                                    accessRights: LongInt): OSErr;
{    Use HSetDirAccess to change the directory access control information    }
{    for a directory on a shared volume.                                        }
{                                                                            }
{    vRefNum            input:    Volume specification.                            }
{    dirID            input:    Directory ID.                                    }
{    name            input:    Pointer to directory name, or nil if dirID        }
{                            specifies the directory.                        }
{    ownerID            output:    The directory's owner ID.                        }
{    groupID            output:    The directory's group ID or                        }
{                            0 if no group affiliation.                        }
{    accessRights    output:    The directory's access rights.                    }


{***************************************************************************}


    FUNCTION FSpSetDirAccess (spec: FSSpec;
                                    ownerID: LongInt;
                                    groupID: LongInt;
                                    accessRights: LongInt): OSErr;
{    Use FSpSetDirAccess to change the directory access control information    }
{    for a directory on a shared volume.                                        }
{                                                                            }
{    spec            input:    An FSSpec record specifying the directory.        }
{    ownerID            output:    The directory's owner ID.                        }
{    groupID            output:    The directory's group ID or                        }
{                            0 if no group affiliation.                        }
{    accessRights    output:    The directory's access rights.                    }


{***************************************************************************}


    FUNCTION HMapID (volName: StringPtr;
                                    vRefNum: Integer;
                                    ID: LongInt;
                                    objType: Integer;
                                    name: StringPtr): OSErr;
{    Use HMapID to determine the name of a user or group if you know the        }
{    user or group ID.                                                        }
{                                                                            }
{    volName        input:    A pointer to the name of a mounted volume            }
{                        or nil.                                                }
{    vRefNum        input:    Volume specification.                                }
{    objType        input:    The mapping function code: 1 if you're mapping a    }
{                        user ID to a user name or 2 if you're mapping a        }
{                        group ID to a group name.                            }
{    name        input:    Points to a buffer (minimum Str31) where the user    }
{                        or group name is to be returned or must be nil.        }
{                output:    The user or group name.                                }


{***************************************************************************}


    FUNCTION HMapName (volName: StringPtr;
                                    vRefNum: Integer;
                                    name: Str255;
                                    objType: Integer;
                                    VAR ID: LongInt): OSErr;
{    Use HMapName to determine the user or group ID if you know the user or    }
{    group name.                                                                }
{                                                                            }
{    volName        input:    A pointer to the name of a mounted volume            }
{                        or nil.                                                }
{    vRefNum        input:    Volume specification.                                }
{    name        input:    The user or group name.                                }
{    objType        input:    The mapping function code: 3 if you're mapping a    }
{                        user name to a user ID or 4 if you're mapping a        }
{                        group name to a group ID.                            }
{    ID            output:    The user or group ID.                                }


{***************************************************************************}


    FUNCTION HCopyFile (srcVRefNum: Integer;
                                    srcDirID: LongInt;
                                    srcName: Str255;
                                    dstVRefNum: Integer;
                                    dstDirID: LongInt;
                                    dstPathname: StringPtr;
                                    copyName: StringPtr): OSErr;
{    Use HCopyFile to duplicate a file and optionally to rename it.            }
{    The source and destination volumes must be on the same file server.        }
{                                                                            }
{    srcVRefNum    input:    Source volume specification.                        }
{    srcDirID    input:    Source directory ID.                                }
{    srcName        input:    Source file name.                                    }
{    dstVRefNum    input:    Destination volume specification.                    }
{    dstDirID    input:    Destination directory ID.                            }
{    dstPathname    input:    Pointer to destination directory name, or            }
{                        nil when dstDirID specifies a directory.            }
{    copyName    input:    Points to the new file name if the file is to be    }
{                        renamed or nil if the file isn't to be renamed.        }


{***************************************************************************}


    FUNCTION FSpCopyFile (srcSpec: FSSpec;
                                    dstSpec: FSSpec;
                                    copyName: StringPtr): OSErr;
{    Use FSpCopyFile to duplicate a file and optionally to rename it.        }
{    The source and destination volumes must be on the same file server.        }
{                                                                            }
{    srcSpec        input:    An FSSpec record specifying the source file.        }
{    dstSpec        input:    An FSSpec record specifying the destination            }
{                        directory.                                            }
{    copyName    input:    Points to the new file name if the file is to be    }
{                        renamed or nil if the file isn't to be renamed.        }


{***************************************************************************}


    FUNCTION HMoveRename (vRefNum: Integer;
                                    srcDirID: LongInt;
                                    srcName: Str255;
                                    dstDirID: LongInt;
                                    dstpathName: StringPtr;
                                    copyName: StringPtr): OSErr;
{    Use HMoveRename to move a file or directory and optionally to rename    }
{    it.  The source and destination locations must be on the same shared    }
{    volume.                                                                    }
{                                                                            }
{    vRefNum        input:    Volume specification.                                }
{    srcDirID    input:    Source directory ID.                                }
{    srcName        input:    The source object name.                                }
{    dstDirID    input:    Destination directory ID.                            }
{    dstName        input:    Pointer to destination directory name, or            }
{                        nil when dstDirID specifies a directory.            }
{    copyName    input:    Points to the new name if the object is to be        }
{                        renamed or nil if the object isn't to be renamed.    }


{***************************************************************************}


    FUNCTION FSpMoveRename (srcSpec: FSSpec;
                                    dstSpec: FSSpec;
                                    copyName: StringPtr): OSErr;
{    Use FSpMoveRename to move a file or directory and optionally to            }
{    rename it. The source and destination locations must be on the same        }
{    shared volume.                                                            }
{                                                                            }
{    srcSpec        input:    An FSSpec record specifying the source object.        }
{    dstSpec        input:    An FSSpec record specifying the destination            }
{                        directory.                                            }
{    copyName    input:    Points to the new name if the object is to be        }
{                        renamed or nil if the object isn't to be renamed.    }


{***************************************************************************}


    FUNCTION GetVolMountInfoSize (volName: StringPtr;
                                    vRefNum: Integer;
                                    VAR size: Integer): OSErr;
{    Use GetVolMountInfoSize to determine the how much space to allocate        }
{    for a volume mounting information record.                                }
{                                                                            }
{    volName        input:    A pointer to the name of a mounted volume            }
{                        or nil.                                                }
{    vRefNum        input:    Volume specification.                                }
{    size        output:    The space needed (in bytes) of the volume mounting    }
{                        information record.                                    }


{***************************************************************************}


    FUNCTION GetVolMountInfo (volName: StringPtr;
                                    vRefNum: Integer;
                                    volMountInfo: Ptr): OSErr;
{    Use GetVolMountInfo to retrieve a volume mounting information record    }
{    containing all the information needed to mount the volume, except        }
{    for passwords.                                                            }
{                                                                            }
{    volName            input:    A pointer to the name of a mounted volume        }
{                            or nil.                                            }
{    vRefNum            input:    Volume specification.                            }
{    volMountInfo    output:    Points to a volume mounting information            }
{                            record where the mounting information is to        }
{                            be returned.                                    }


{***************************************************************************}


    FUNCTION VolumeMount (volMountInfo: Ptr;
                                    VAR vRefNum: Integer): OSErr;
{    Use VolumeMount to mount a volume using a volume mounting information    }
{    record.                                                                    }
{                                                                            }
{    volMountInfo    inout:    Points to a volume mounting information record.    }
{    vRefNum            output:    A volume reference number.                        }


{***************************************************************************}


    FUNCTION Share (vRefNum: Integer;
                                    dirID: LongInt;
                                    name: StringPtr): OSErr;
{    Use Share to establish a local volume or directory as a share point.    }
{                                                                            }
{    vRefNum            input:    Volume specification.                            }
{    dirID            input:    Directory ID.                                    }
{    name            input:    Pointer to directory name, or nil if dirID        }
{                            specifies the directory.                        }


{***************************************************************************}


    FUNCTION FSpShare (spec: FSSpec): OSErr;
{    Use FSpShare to establish a local volume or directory as a share point.    }
{                                                                            }
{    spec    input:    An FSSpec record specifying the share point.            }


{***************************************************************************}


    FUNCTION Unshare (vRefNum: Integer;
                                    dirID: LongInt;
                                    name: StringPtr): OSErr;
{    Use Unshare to remove a share point.                                    }
{                                                                            }
{    vRefNum            input:    Volume specification.                            }
{    dirID            input:    Directory ID.                                    }
{    name            input:    Pointer to directory name, or nil if dirID        }
{                            specifies the directory.                        }


{***************************************************************************}


    FUNCTION FSpUnshare (spec: FSSpec): OSErr;
{    Use FSpUnshare to remove a share point.                                    }
{                                                                            }
{    spec    input:    An FSSpec record specifying the share point.            }


{***************************************************************************}


    FUNCTION GetUGEntry (objType: Integer;
                                    objName: StringPtr;
                                    VAR objID: LongInt): OSErr;
{    Use GetUGEntry to get a list of user or group entries from the            }
{    local file server.                                                        }
{                                                                            }
{    objType        input:    The object type: -1 = group; 0 = user                }
{    objName        input:    Points to a buffer (minimum Str31) where the user    }
{                        or group name is to be returned or must be nil.        }
{                output:    The user or group name.                                }
{    objID        input:    O to get the first user or group. If the entry        }
{                        objID last returned by GetUGEntry is passed, then    }
{                        user or group whose alphabetically next in the list    }
{                        of entries is returned.                                }
{                output:    The user or group ID.                                }


{***************************************************************************}

IMPLEMENTATION

END.